---
title: Rating Group
description: Using the rating machine in your project.
package: "@zag-js/rating-group"
---

Rating group allows a user to assign rating to an item within a product.

<Resources pkg="@zag-js/rating-group" />

<Showcase id="Rating" />

**Features**

- Support for syncing `disabled` state of with `fieldset` element
- Support for form `reset` events

## Installation

To use the rating group machine in your project, run the following command in
your command line:

<CodeSnippet id="rating-group/installation.mdx" />

## Anatomy

To set up the rating correctly, you'll need to understand its anatomy and how we
name its parts.

> Each part includes a `data-part` attribute to help identify them in the DOM.

<Anatomy id="rating-group" />

## Usage

First, import the rating package into your project

```jsx
import * as rating from "@zag-js/rating-group"
```

The rating package exports two key functions:

- `machine` — The state machine logic for the rating widget.
- `connect` — The function that translates the machine's state to JSX attributes
  and event handlers.

> You'll also need to provide a unique `id` to the `useMachine` hook. This is
> used to ensure that every part has a unique identifier.

Next, import the required hooks and functions for your framework and use the
rating machine in your project 🔥

<CodeSnippet id="rating-group/usage.mdx" />

### Disabling the rating group

To make rating disabled, set the context's `disabled` property to true

```jsx {2}
const service = useMachine(rating.machine, {
  disabled: true,
})
```

### Making the rating readonly

To make rating readonly, set the context's `readOnly` property to true

```jsx {2}
const service = useMachine(rating.machine, {
  readOnly: true,
})
```

### Setting the initial value

Use the `defaultValue` property to set the rating's initial value.

```jsx {2}
const service = useMachine(rating.machine, {
  defaultValue: 2.5,
})
```

### Listening for changes

When the rating value changes, the `onValueChange` callback is invoked.

```jsx {2-7}
const service = useMachine(rating.machine, {
  onValueChange({ value }) {
    console.log("rating value is:", value)
    // '1' | '2.5' | '4'
  },
})
```

### Usage within forms

To use rating within forms, use the exposed `inputProps` from the `connect`
function and ensure you pass `name` value to the machine's context. It will
render a hidden input and ensure the value changes get propagated to the form
correctly.

```jsx {2}
const service = useMachine(rating.machine, {
  name: "rating",
})
```

## Styling guide

Earlier, we mentioned that each rating part has a `data-part` attribute added to
them to select and style them in the DOM.

### Disabled State

When the rating is disabled, the `data-disabled` attribute is added to the
rating, control and label parts.

```css
[data-part="rating"][data-disabled] {
  /* styles for rating disabled state */
}

[data-part="label"][data-disabled] {
  /* styles for rating control disabled state */
}

[data-part="input"][data-disabled] {
  /* styles for rating label disabled state */
}
```

### Checked State

When the rating is checked, the `data-checked` attribute is added to the rating
part.

```css
[data-part="rating"][data-checked] {
  /* styles for rating checked state */
}
```

### Readonly State

When the rating is readonly, the `data-readonly` attribute is added to the
rating part.

```css
[data-part="rating"][data-readonly] {
  /* styles for rating readonly state */
}
```

### Highlighted

When a rating is highlighted, the `data-highlighted` attribute is added to the
rating part.

```css
[data-part="rating"][data-highlighted] {
  /* styles for highlighted rating */
}
```

### Half rating

When a rating is half, the `data-half` attribute is added to the rating part.

```css
[data-part="rating"][data-half] {
  /* styles for half rating */
}
```

## Methods and Properties

### Machine Context

The rating group machine exposes the following context properties:

<ContextTable name="rating-group" />

### Machine API

The rating group `api` exposes the following methods:

<ApiTable name="rating-group" />

### Data Attributes

<DataAttrTable name="rating-group" />

## Accessibility

### Keyboard Interactions

<KeyboardTable name="rating-group" />
